options</see></indexterm>The controls setting for a theme determines the visual
appearance of windows, panels, and applets. The controls setting also determines
the visual appearance of the GNOME-compliant interface items that appear on
windows, panels, and applets, such as menus, icons, and buttons. Some of the
controls setting options that are available are designed for special accessibility
needs. Users can choose an option for the controls setting from the <guilabel>Controls</guilabel> tabbed section in the <application>Theme</application>
a theme determines the appearance of the frames around windows only. Users
can choose an option for the window frame setting from the <guilabel>Window
Border</guilabel> tabbed section in the <application>Theme</application> preference
tool.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Icon</term>
<listitem>
<para><indexterm><primary>themes</primary><secondary>icons options</secondary><tertiary>introduction</tertiary></indexterm><indexterm><primary>icon themes</primary><see>themes, icons options</see></indexterm>The icon setting for a theme determines the appearance of
the icons on panels and the desktop background. Users can choose an option
for the icon setting from the <guilabel>Icons</guilabel> tabbed section in
the <application>Theme</application> preference tool.</para>
</listitem>
</varlistentry>
</variablelist>
</sect1>
<sect1 id="themes-17">
<title>Theme Index File</title>
<para>Each theme has an index file which defines the characteristics of the
theme. The name of the index file is <filename>/usr/share/themes/<replaceable>theme-name</replaceable>/index.theme</filename>. </para>
<para>The following is a sample theme index file:</para>
<programlisting>[Desktop Entry]
Type=X-GNOME-Metatheme
Name=High Contrast Large
Name[es]=Alto contraste grande
Comment=Large black-on-white text and icons
Comment[es]=Textos e iconos grandes en negro sobre blanco
Encoding=UTF-8
[X-GNOME-Metatheme]
GtkTheme=HighContrastLargePrint
IconTheme=HighContrast
MetacityTheme=Atlanta
ApplicationFont=sans 18
</programlisting>
<para>The following table describes the keys in theme index files:</para>
<table frame="topbot" id="themes-TBL-18">
<title>Keys in Theme Index Files</title>
<tgroup cols="2" colsep="0" rowsep="0">
<colspec colname="colspec0" colwidth="33*"/>
<colspec colname="colspec1" colwidth="67*"/>
<thead>
<row rowsep="1">
<entry>
<para>Index File Key</para>
</entry>
<entry>
<para>Description</para>
</entry>
</row>
</thead>
<tbody>
<row>
<entry colname="colspec0" valign="top">
<para>
<literal>Type</literal>
</para>
</entry>
<entry colname="colspec1" valign="top">
<para>Specifies that this theme determines
the appearance of several theme options, such as controls, window frames,
and icons.</para>
</entry>
</row>
<row>
<entry colname="colspec0" valign="top">
<para>
<literal>Name</literal>
</para>
</entry>
<entry colname="colspec1" valign="top">
<para>The name of the theme. This is
the name of the theme that is displayed in the <application>Theme</application>
preference tool.</para>
</entry>
</row>
<row>
<entry colname="colspec0" valign="top">
<para>
<literal>Comment</literal>
</para>
</entry>
<entry colname="colspec1" valign="top">
<para>A brief description of the theme.
This is the text that is displayed under the name of the theme in the <application>Theme</application> preference tool.</para>
</entry>
</row>
<row>
<entry valign="top">
<para>
<literal>GtkTheme</literal>
</para>
</entry>
<entry valign="top">
<para>Corresponds to the controls setting in the <application>Theme</application> preference tool. Specifies which controls setting option
to apply to windows, panels, and applets.</para>
</entry>
</row>
<row>
<entry valign="top">
<para>
<literal>IconTheme</literal>
</para>
</entry>
<entry valign="top">
<para>Corresponds to the icons setting in the <application>Theme</application> preference tool. Specifies which icons setting option
to apply to panels and the desktop background.</para>
</entry>
</row>
<row>
<entry valign="top">
<para>
<literal>MetacityTheme</literal>
</para>
</entry>
<entry valign="top">
<para>Corresponds to the window frame setting in the <application>Theme</application> preference tool. Specifies which window frame setting
option to apply to windows.</para>
</entry>
</row>
<row>
<entry colname="colspec0" valign="top">
<para>
<literal>ApplicationFont</literal>
</para>
</entry>
<entry colname="colspec1" valign="top">
<para>Corresponds to the application font setting in the <application>Font</application>
preference tool.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</sect1>
<sect1 id="themes-3">
<title>To Install a New Controls Option</title>
<indexterm>
<primary>themes</primary>
<secondary>controls options</secondary>
<tertiary>installing</tertiary>
</indexterm>
<para>You can add a new option
for the controls setting in the <application>Theme</application> preference
tool. Controls options reside in the <filename>/usr/share/themes</filename>
directory. The typical structure of a controls option in the file system is
<para>Typically, a new option for the controls setting is supplied
as a <filename>.tar.gz</filename> file. To install the new controls option,
unzip the <filename>.tar.gz</filename> file, then untar the <filename>.tar</filename> file into the <filename>/usr/share/themes</filename> directory.</para>
<para>Users can install their own options for the controls setting. If a user
installs an option for the controls setting, the option is stored in the <filename>$HOME/.themes</filename> directory.</para>
</sect1>
<sect1 id="themes-5">
<title>To Install a New Window Frame Option</title>
<indexterm>
<primary>themes</primary>
<secondary>window frame options</secondary>
<tertiary>installing</tertiary>
</indexterm>
<para>You can add a new option
for the window frame setting in the <application>Theme</application> preference
tool. Window frame options reside in the <filename>/usr/share/themes/<replaceable>option-name</replaceable>/metacity-1</filename> directory. The typical structure
of a window frame option in the file system is as follows:</para>
<para>Typically, a new option for the window frame setting
is supplied as a <filename>.tar.gz</filename> file. To install the new window
frame option, unzip the <filename>.tar.gz</filename> file, then untar the <filename>.tar</filename> file into the <filename>/usr/share/themes</filename> directory.</para>
<para>Users can install their own options for the window frame setting. If
a user installs an option for the window frame setting, the option is stored
in the <filename>$HOME/.themes</filename> directory.</para>
</sect1>
<sect1 id="themes-16">
<title>To Install a New Icons Option</title>
<indexterm>
<primary>themes</primary>
<secondary>icons options</secondary>
<tertiary>installing</tertiary>
</indexterm>
<para>You can add a new option for the icons
setting in the <application>Theme</application> preference tool. Icons options
reside in the <filename>/usr/share/icons/<replaceable>option-name</replaceable></filename>
directory. The typical structure of an icons option in the file system is
<para>Typically, a new option for the icons setting is supplied
as a <filename>.tar.gz</filename> file. To install the new icons option, unzip
the <filename>.tar.gz</filename> file, then untar the <filename>.tar</filename>
file into the <filename>/usr/share/icons</filename> directory.</para>
<para>Users can install their own options for the icons setting. If a user
installs an option for the icons setting, the option is stored in the <filename>$HOME/.icons/<replaceable>option-name</replaceable></filename> directory.</para>
</sect1>
<sect1 id="themes-11">
<title>Installing Icons for Themes</title>
<indexterm>
<primary>themes</primary>
<secondary>installing icons</secondary>
</indexterm>
<para>The GNOME Desktop provides several themes that are designed
for users with special visual needs. For example, some of the themes are designed
for users with low vision. Several versions of icons might be required so
that the icon can be displayed properly in each theme.</para>
<para>You might need to install a new icon for an application. When you install
a new icon, you must create several versions of the icon, so that the icon
displays correctly in the themes. You must create several versions of the
following types of icon:</para>
<itemizedlist>
<listitem>
<para>Icons that are used within applications in the GNOME Desktop.</para>
</listitem>
<listitem>
<para>Icons that are used internally by GTK+ applications, or GTK+
stock icons.</para>
</listitem>
</itemizedlist>
<para>When you install a new icon, you must create several versions of the
icon, so that the icon displays correctly in the themes. You can create the
icons in several formats, for example Portable Network Graphic (PNG) format.
The suggested size of icons for the desktop environment is 48 pixels by 48
pixels. At this size, most themes can rescale the icons.</para>
<para>When you install a new icon, create the following 48 pixel by 48 pixel
versions of the icon:</para>
<itemizedlist>
<listitem>
<para>Regular icon</para>
</listitem>
<listitem>
<para>Low contrast icon</para>
</listitem>
<listitem>
<para>High contrast icon</para>
</listitem>
<listitem>
<para>Inverse high contrast icon</para>
</listitem>
</itemizedlist>
<para>If possible, create 16 pixel by 16 pixel versions of the each of the
icons above also, for themes that do not require large print.</para>
<para>Install the icons to the image files location that is specified for
the theme in <xref linkend="themes-3"/> or <xref linkend="themes-5"/>. For example,
to add icons to the HighContrastLargePrint theme, add the icons to the <filename>/usr/share/themes/HighContrastLargePrint/pixmaps</filename> directory. Add
references to the icons to the relevant theme files. For example, to add icons
to the HighContrastLargePrint theme, add references to the icons to the <filename>/usr/share/themes/HighContrastLargePrint/gtk-2.0/gtkrc</filename> file. Modify
the <filename>gtkrc</filename> file for the theme to associate the icon with
a GTK stock icon identifier.<!--More info required from Calum.--></para>
<para>For more information on how to create icons for application launchers
and for panels, see <ulink url="http://www.freedesktop.org/Standards/icon-theme-spec">http://www.freedesktop.org/Standards/icon-theme-spec</ulink>.</para>
</sect1>
<sect1 id="themes-15">
<title>To Create a Custom Controls Option</title>
<indexterm>
<primary>themes</primary>
<secondary>controls options</secondary>
<tertiary>creating custom</tertiary>
</indexterm>
<para>If the options for the
controls setting are not suitable for the needs of your users, you can create
a custom controls option. To create a custom controls option, perform the
following steps:</para>
<orderedlist>
<listitem>
<para>Create a directory structure for the option in the <filename>/usr/share/themes</filename> directory. Use the same directory structure that
other options use. For example, to create an option that is called SmallPrint,
<para>Locate the <filename>gtkrc</filename> file that is closest
to meeting the needs of your users. Copy the file to the <filename>gtk-2.0</filename> directory of your new option.</para>
</listitem>
<listitem>
<para>Open the <filename>gtkrc</filename> file in a text editor,
and modify the attributes of the interface elements as required. </para>
</listitem>
<listitem>
<para>If the new option includes images, install the images for
the new option in the <filename>pixmaps</filename> directory of your new option.
If the new option uses images from another option, you do not need to create
copies of the images for the new option. Instead, ensure that the reference
to the images in the <literal>pixmap_path</literal> entry in the <filename>gtkrc</filename> file is correct.</para>
</listitem>
</orderedlist>
<para>Users can now choose the new option for the controls setting.</para>
<para>For more information on <filename>gtkrc</filename> files, see <ulink url="http://developer.gnome.org/doc/API/2.0/gtk/index.html">http://developer.gnome.org/doc/API/2.0/gtk/index.html</ulink>.</para>
